The Payment Intent API allows merchants to retrieve a list of saved cards for a customer and create end-points so that they can go directly to the payment page circumventing the requirement to navigate through the payment-type checkout UX. They can also customise the UX on their platform to present the saved cards to the customer as part of their checkout journey. The actual capture of the credit card CVV and 3DSecure remains the responsibility of the Payment Gateway however for PCI-DSS compliance purposes.
Merchants who want to request the available payment types and a customer’s saved cards, can request a payment intent from the payment gateway. Following the provided endpoints from the API will allow the merchant to go directly to the selected payment path.
Please note that these endpoints require Basic Auth in the header for authentication (See Appendix I) and you must specify your merchant payserver username and password. The Basic Auth authentication details must correspond with the payserver details included in the encrypted transaction object.
| URL Type | URL Value |
|---|---|
| Test (QA) Post Endpoint | https://qa.vodacompaymentgateway.co.za/api/pay/intent |
| Live (PROD) Post Endpoint | https://psp.vodacompaymentgateway.co.za/api/pay/intent |
The payment intent Request API requires the following payload to be passed. Please ensure that the EncXML/EncJSON complies fully with the encrypted transaction object requirements as per 3.2 Step 1: Create Transaction Object of this document.
Please note that these endpoints require Basic Auth in the header for authentication (See Appendix I).
| Field Name (Case–Sensitive) |
Type(max length) | Required MandatoryOptional |
Description |
|---|---|---|---|
| EncIV | String | O | Random string used by merchant used as the Initialisation Vector to encrypt the message passed in encXML/encJSON and used by Vodacom to decrypt the message Mandatory if encType is TWOFISH or AES. |
| EncType | String | O | This is encryption algorithm the merchant has elected to use. Permitted Values: AES BLOWFISH (Recommended) TWOFISH (if omitted default value is BLOWFISH) |
| EncXML | String | O | The encrypted XML Transaction object created in step 1 and 2 must be passed in this field. (Mandatory if encrypted payload is XML) |
| EncJSON | String | O | The encrypted JSON Transaction object created in step 1 and 2 must be passed in this field. (Mandatory if encrypted payload is JSON) |
| EncIterations | Numeric | O | Number of iterations used to derive the key (along with the salt and stored encryption key) using password–based key derivation functionality, PBKDF2 Mandatory if encType is TWOFISH or AES. |
| EncSalt | String | O | Random string used by merchant to salt the password used to encrypt the message passed in encXML/encJSON and used by Vodacom to decrypt the message Mandatory if encType is TWOFISH or AES |
| Username | String | M | Merchant Technical users VPG account username. |
| RedirectUrl | String | O | Redirect URL for unsuccessful transactions. Overrides existing URL if value is passed. See 3.7.3. Merchant Notification POST Fields Note, this is a synchronous HTTPS POST that happens on Form submit from the client's browser. |
| CompleteUrl | String | O | Response URL for successful transactions. Overrides existing URL if value is passed. See 3.7.3. Merchant Notification POST Fields Note, this is a synchronous HTTPS POST that happens on Form submit from the client's browser. |
| NotifyUrl | String | M | This is the URL to which asynchronous callbacks are sent. See 3.7.4. Asynchronous Call–back. Note, in order for this to function, firewall ports must be opened on the Payment Gateway to post–back to your server. This server–to–server post-back has built in guaranteed delivery and retry queuing until an HTTP 200 response is received from the merchant. |
| Field Name (Case–Sensitive) |
Type | Description |
|---|---|---|
| SavedCards | List | A list of saved cards associated with the customer identifier sent in the request. |
| CustomerSavedCard | Object | Details of each card saved by a customer for this merchant |
| CustomerSavedCard.HeaderId | String | Identifier for tokenized card in Card Vault |
| CustomerSavedCard.MerchantTokenId | String | Merchant identifier in Card Vault |
| CustomerSavedCard.MaskedPan | String | Masked Pan of the tokenized card. Mask is based on the card type. |
| CustomerSavedCard.CardType | String | Indicating whether the card is Visa, Mastercard, Amex or Diners |
| CustomerSavedCard.Disabled | Bool | Flag indicating if the card is active for the customer to use |
| CustomerSavedCard.DateAdded | DateTime | Date the saved card was tokenize in the Card Vault |
| CustomerSavedCard.IsDefault | Bool | Flag indicating whether the saved card is the users default card |
| CustomerSavedCard.CardAlias | String | The Alias (Name) given to the card by the customer in the save journey |
| SavedCards .EncryptedToken | String | Encrypted token of the tokenized card that can be pass to the portal to in the payment journey. |
| SavedCards.Disabled | Bool | Flag indicating if the card is active for the customer to use |
| SavedCards .CardDisplayText | String | The sanitized Alias (description) given to the card by the customer in the save journey |
| SavedCards.PaymentUrl | String | Endpoint which the merchant can navigate the customer directly to the payment checkout page, auto-selecting the chosen saved card for the customer. |
| PaymentTypes | List | List of merchant specific payment types active to the merchant. |
| PaymentTypes .Name | String | Internal Name of the payment type |
| PaymentTypes.Description/td> | String | Payment type description useful for UX presentation |
| PaymentTypes.PaymentUrl | String | An endpoint to which the merchant can direct the customer to, by-passing the payment-type option page and auto-selecting the chosen payment-type. |
| PaymentUrl | String | An endpoint to which the merchant can direct the customer to, without selecting any specific journey. This is the same end-point as if the merchant had called the normal checkout end-point as mentioned in 3.5.1 HTML Form Post Endpoints without reference to any particular payment type or saved card. |
| NewCardUrl | String | An endpoint to which the merchant can navigate to, in order to allow the customer to save a new card without reference to a payment checkout. Please review 3.10 Save Card Only Journey (Optional) for further detail. |
| RemoveCardUrl | String | An endpoint to which the merchant can navigate to, in order to allow the customer to remove a previously saved card. Please review 3.11 Delete Saved Card (Optional) for further detail. |
| WasSuccessful | Bool | Flag indicating the result of the payment intent request |